{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "5e3d4685",
   "metadata": {},
   "source": [
    "# Agentic retrieval using Azure AI Search and Azure AI Agent Service\n",
    "\n",
    "Use this notebook to create an agentic retrieval pipeline built on Azure AI Search and an Azure AI Agent.\n",
    "\n",
    "In this walkthrough, you will:\n",
    "\n",
    "+ Create an \"earth_at_night\" search index\n",
    "+ Load it with documents from a GitHub URL\n",
    "+ Create a knowledge source that points to searchable content.\n",
    "+ Create a knowledge agent on Azure AI Search that points to a knowledge source and an LLM for intelligent query planning\n",
    "+ Create a Foundry agent in Azure AI Foundry to determine when queries are needed\n",
    "+ Create a Azure AI Agent tool (client) to orchestrate all requests\n",
    "+ Start a chat with the agent\n",
    "\n",
    "This notebook is referenced in [Build an agentic retrieval pipeline in Azure AI Search](https://learn.microsoft.com/azure/search/search-agentic-retrieval-how-to-pipeline).\n",
    "\n",
    "This exercise differs from the [Agentic Retrieval Quickstart](https://learn.microsoft.com/azure/search/search-get-started-agentic-retrieval) in how it uses Azure AI Agent to determine whether to retrieve data from the index, and how it uses an agent tool for orchestration."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ecd68a6e",
   "metadata": {},
   "source": [
    "## Prerequisites\n",
    "\n",
    "+ Azure AI Search, basic tier or higher, in [any region that supports semantic ranker](https://learn.microsoft.com/azure/search/search-region-support#azure-public-regions).\n",
    "\n",
    "+ Azure OpenAI, and you should have an **Azure AI Developer** role assignment to create a Foundry project.\n",
    "\n",
    "+ An [Azure AI agent and Foundry project](https://learn.microsoft.com/azure/ai-services/agents/quickstart?pivots=ai-foundry-portal), created in the Azure AI Foundry portal, with the basic setup, used for creating the Foundry agent.\n",
    "\n",
    "+ A deployment of a [supported model](https://learn.microsoft.com/azure/search/search-agentic-retrieval-how-to-create#supported-models) in your Foundry project. This notebook uses gpt-4o-mini. We recommend 100,000 token capacity. You can find capacity and the rate limit in the model deployments list in the Azure AI Foundry portal.\n",
    "\n",
    "We recommend creating a virtual environment to run this sample code. In Visual Studio Code, open the control palette (ctrl-shift-p) to create an environment. This notebook was tested on Python 3.13.7."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1f40a871",
   "metadata": {},
   "source": [
    "## Set up connections\n",
    "\n",
    "Save the `sample.env` file as `.env` and then modify the environment variables to use your Azure endpoints. You need endpoints for:\n",
    "\n",
    "+ Azure AI Search\n",
    "+ Azure OpenAI\n",
    "+ Azure AI Foundry project\n",
    "\n",
    "You can find endpoints for Azure AI Search and Azure OpenAI in the [Azure portal](https://portal.azure.com).\n",
    "\n",
    "You can find the project endpoint in the Azure AI Foundry portal:\n",
    "\n",
    "1. Sign in to the [Azure AI Foundry portal](https://ai.azure.com) and open your project. \n",
    "\n",
    "1. In the **Overview** tile, find and copy the **Azure AI Foundry project endpoint**. \n",
    "\n",
    "   A hypothetical endpoint might look like this: `https://your-foundry-resource.services.ai.azure.com/api/projects/your-foundry-project`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "679bc80a",
   "metadata": {},
   "source": [
    "## Load Connections\n",
    "\n",
    "Load the environment variables to set up connections and object names."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "e42b4a10",
   "metadata": {},
   "outputs": [],
   "source": [
    "from dotenv import load_dotenv\n",
    "from azure.identity import DefaultAzureCredential, get_bearer_token_provider\n",
    "import os\n",
    "\n",
    "load_dotenv(override=True) # take environment variables from .env.\n",
    "\n",
    "# The following variables from your .env file are used in this notebook\n",
    "project_endpoint = os.environ[\"PROJECT_ENDPOINT\"]\n",
    "agent_model = os.getenv(\"AGENT_MODEL\", \"gpt-4.1-mini\")\n",
    "endpoint = os.environ[\"AZURE_SEARCH_ENDPOINT\"]\n",
    "credential = DefaultAzureCredential()\n",
    "token_provider = get_bearer_token_provider(credential, \"https://search.azure.com/.default\")\n",
    "knowledge_source_name = os.getenv(\"AZURE_SEARCH_KNOWLEDGE_SOURCE_NAME\", \"earth-at-night-ks\")\n",
    "index_name = os.getenv(\"AZURE_SEARCH_INDEX\", \"earth_at_night\")\n",
    "azure_openai_endpoint = os.environ[\"AZURE_OPENAI_ENDPOINT\"]\n",
    "azure_openai_gpt_deployment = os.getenv(\"AZURE_OPENAI_GPT_DEPLOYMENT\", \"gpt-4.1-mini\")\n",
    "azure_openai_gpt_model = os.getenv(\"AZURE_OPENAI_GPT_MODEL\", \"gpt-4.1-mini\")\n",
    "azure_openai_embedding_deployment = os.getenv(\"AZURE_OPENAI_EMBEDDING_DEPLOYMENT\", \"text-embedding-3-large\")\n",
    "azure_openai_embedding_model = os.getenv(\"AZURE_OPENAI_EMBEDDING_MODEL\", \"text-embedding-3-large\")\n",
    "agent_name = os.getenv(\"AZURE_SEARCH_AGENT_NAME\", \"earth-search-agent\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ea2ecdce",
   "metadata": {},
   "source": [
    "## Create search index on Azure AI Search\n",
    "\n",
    "This steps create a search index that contains plain text and vector content. You can use any existing search index, but it must meet the [criteria for agentic retrieval workloads](https://learn.microsoft.com/azure/search/search-agentic-retrieval-how-to-index). The primary schmea requirement is that is has a semantic configuration, with a `default_configuration_name`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "91fd6810",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Index 'earth_at_night' created or updated successfully\n"
     ]
    }
   ],
   "source": [
    "from azure.search.documents.indexes.models import SearchIndex, SearchField, VectorSearch, VectorSearchProfile, HnswAlgorithmConfiguration, AzureOpenAIVectorizer, AzureOpenAIVectorizerParameters, SemanticSearch, SemanticConfiguration, SemanticPrioritizedFields, SemanticField\n",
    "from azure.search.documents.indexes import SearchIndexClient\n",
    "\n",
    "index = SearchIndex(\n",
    "    name=index_name,\n",
    "    fields=[\n",
    "        SearchField(name=\"id\", type=\"Edm.String\", key=True, filterable=True, sortable=True, facetable=True),\n",
    "        SearchField(name=\"page_chunk\", type=\"Edm.String\", filterable=False, sortable=False, facetable=False),\n",
    "        SearchField(name=\"page_embedding_text_3_large\", type=\"Collection(Edm.Single)\", stored=False, vector_search_dimensions=3072, vector_search_profile_name=\"hnsw_text_3_large\"),\n",
    "        SearchField(name=\"page_number\", type=\"Edm.Int32\", filterable=True, sortable=True, facetable=True)\n",
    "    ],\n",
    "    vector_search=VectorSearch(\n",
    "        profiles=[VectorSearchProfile(name=\"hnsw_text_3_large\", algorithm_configuration_name=\"alg\", vectorizer_name=\"azure_openai_text_3_large\")],\n",
    "        algorithms=[HnswAlgorithmConfiguration(name=\"alg\")],\n",
    "        vectorizers=[\n",
    "            AzureOpenAIVectorizer(\n",
    "                vectorizer_name=\"azure_openai_text_3_large\",\n",
    "                parameters=AzureOpenAIVectorizerParameters(\n",
    "                    resource_url=azure_openai_endpoint,\n",
    "                    deployment_name=azure_openai_embedding_deployment,\n",
    "                    model_name=azure_openai_embedding_model\n",
    "                )\n",
    "            )\n",
    "        ]\n",
    "    ),\n",
    "    semantic_search=SemanticSearch(\n",
    "        default_configuration_name=\"semantic_config\",\n",
    "        configurations=[\n",
    "            SemanticConfiguration(\n",
    "                name=\"semantic_config\",\n",
    "                prioritized_fields=SemanticPrioritizedFields(\n",
    "                    content_fields=[\n",
    "                        SemanticField(field_name=\"page_chunk\")\n",
    "                    ]\n",
    "                )\n",
    "            )\n",
    "        ]\n",
    "    )\n",
    ")\n",
    "\n",
    "index_client = SearchIndexClient(endpoint=endpoint, credential=credential)\n",
    "index_client.create_or_update_index(index)\n",
    "print(f\"Index '{index_name}' created or updated successfully\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "376b9785",
   "metadata": {},
   "source": [
    "## Upload sample documents\n",
    "\n",
    "This sample uses data from NASA's Earth at Night e-book. It's retrieved from the sample data GitHub repository and passed to the search client for indexing."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "f98f31e7",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Documents uploaded to index 'earth_at_night'\n"
     ]
    }
   ],
   "source": [
    "import requests\n",
    "from azure.search.documents import SearchIndexingBufferedSender\n",
    "\n",
    "url = \"https://raw.githubusercontent.com/Azure-Samples/azure-search-sample-data/refs/heads/main/nasa-e-book/earth-at-night-json/documents.json\"\n",
    "documents = requests.get(url).json()\n",
    "\n",
    "with SearchIndexingBufferedSender(endpoint=endpoint, index_name=index_name, credential=credential) as client:\n",
    "    client.upload_documents(documents=documents)\n",
    "\n",
    "print(f\"Documents uploaded to index '{index_name}'\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "38c2d9d5",
   "metadata": {},
   "source": [
    "## Create a knowledge source\n",
    "\n",
    "This step creates a knowledge source that targets the index you previously created. In the next step, you create a knowledge agent that uses the knowledge source to orchestrate agentic retrieval.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "0cf01881",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Knowledge source 'earth-at-night-ks' created or updated successfully.\n"
     ]
    }
   ],
   "source": [
    "from azure.search.documents.indexes.models import SearchIndexKnowledgeSource, SearchIndexKnowledgeSourceParameters\n",
    "from azure.search.documents.indexes import SearchIndexClient\n",
    "\n",
    "ks = SearchIndexKnowledgeSource(\n",
    "    name=knowledge_source_name,\n",
    "    description=\"Knowledge source for Earth at night data\",\n",
    "    search_index_parameters=SearchIndexKnowledgeSourceParameters(\n",
    "        search_index_name=index_name,\n",
    "        source_data_select=\"id,page_chunk,page_number\",\n",
    "    ),\n",
    ")\n",
    "\n",
    "index_client = SearchIndexClient(endpoint=endpoint, credential=credential)\n",
    "index_client.create_or_update_knowledge_source(knowledge_source=ks)\n",
    "print(f\"Knowledge source '{knowledge_source_name}' created or updated successfully.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e3d0081e",
   "metadata": {},
   "source": [
    "## Create a knowledge agent on Azure AI Search\n",
    "\n",
    "This step creates a knowledge agent, which acts as a wrapper for your knowledge source and LLM deployment.\n",
    "\n",
    "EXTRACTIVE_DATA is the default modality and returns content from your knowledge sources without generative alteration. However, this quickstart uses the ANSWER_SYNTHESIS modality for LLM-generated [answers that cite the retrieved content](https://learn.microsoft.com/azure/search/search-agentic-retrieval-how-to-synthesize)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "fbe31e32",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Knowledge agent 'earth-search-agent' created or updated successfully\n"
     ]
    }
   ],
   "source": [
    "from azure.search.documents.indexes.models import KnowledgeAgent, KnowledgeAgentAzureOpenAIModel, KnowledgeSourceReference, AzureOpenAIVectorizerParameters, KnowledgeAgentOutputConfiguration, KnowledgeAgentOutputConfigurationModality\n",
    "from azure.search.documents.indexes import SearchIndexClient\n",
    "\n",
    "aoai_params = AzureOpenAIVectorizerParameters(\n",
    "    resource_url=azure_openai_endpoint,\n",
    "    deployment_name=azure_openai_gpt_deployment,\n",
    "    model_name=azure_openai_gpt_model,\n",
    ")\n",
    "\n",
    "output_cfg = KnowledgeAgentOutputConfiguration(\n",
    "    modality=KnowledgeAgentOutputConfigurationModality.EXTRACTIVE_DATA,\n",
    "    include_activity=True,\n",
    ")\n",
    "\n",
    "agent = KnowledgeAgent(\n",
    "    name=agent_name,\n",
    "    models=[KnowledgeAgentAzureOpenAIModel(azure_open_ai_parameters=aoai_params)],\n",
    "    knowledge_sources=[\n",
    "        KnowledgeSourceReference(\n",
    "            name=knowledge_source_name,\n",
    "            include_reference_source_data=True,\n",
    "            include_references=True\n",
    "        )\n",
    "    ],\n",
    "    output_configuration=output_cfg,\n",
    ")\n",
    "\n",
    "\n",
    "index_client = SearchIndexClient(endpoint=endpoint, credential=credential)\n",
    "index_client.create_or_update_agent(agent)\n",
    "print(f\"Knowledge agent '{agent_name}' created or updated successfully\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ff845de0",
   "metadata": {},
   "source": [
    "## Create an Azure AI Agent\n",
    "\n",
    "In the Azure AI Foundry, an agent is a smart micro-service that can do RAG. The purpose of this specific agent is to decide when to send a query to the agentic retrieval pipeline."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "6eb0ebd3",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[]"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from azure.ai.projects import AIProjectClient\n",
    "\n",
    "project_client = AIProjectClient(endpoint=project_endpoint, credential=credential)\n",
    "\n",
    "list(project_client.agents.list_agents())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "aa363122",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "AI agent 'earth-search-agent' created or updated successfully\n"
     ]
    }
   ],
   "source": [
    "instructions = \"\"\"\n",
    "A Q&A agent that can answer questions about the Earth at night.\n",
    "Sources have a JSON format with a ref_id that must be cited in the answer using the format [ref_id].\n",
    "If you do not have the answer, respond with \"I don't know\".\n",
    "\"\"\"\n",
    "agent = project_client.agents.create_agent(\n",
    "    model=agent_model,\n",
    "    name=agent_name,\n",
    "    instructions=instructions\n",
    ")\n",
    "\n",
    "print(f\"AI agent '{agent_name}' created or updated successfully\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f12a051e",
   "metadata": {},
   "source": [
    "## Add an agentic retrieval tool to AI Agent\n",
    "\n",
    "An end-to-end pipeline needs an orchestration mechanism for coordinating calls to the retriever and agent. The pattern described in this notebook uses a [tool](https://learn.microsoft.com/azure/ai-services/agents/how-to/tools/function-calling) for this task. The tool calls the Azure AI Search knowledge retrieval client and the Azure AI agent, and it drives the conversations with the user."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "de2ee775",
   "metadata": {},
   "outputs": [],
   "source": [
    "from azure.ai.agents.models import FunctionTool, ToolSet, ListSortOrder\n",
    "\n",
    "from azure.search.documents.agent import KnowledgeAgentRetrievalClient\n",
    "from azure.search.documents.agent.models import KnowledgeAgentRetrievalRequest, KnowledgeAgentMessage, KnowledgeAgentMessageTextContent\n",
    "\n",
    "agent_client = KnowledgeAgentRetrievalClient(endpoint=endpoint, agent_name=agent_name, credential=credential)\n",
    "\n",
    "thread = project_client.agents.threads.create()\n",
    "retrieval_results = {}\n",
    "\n",
    "def agentic_retrieval() -> str:\n",
    "    \"\"\"\n",
    "        Searches a NASA e-book about images of Earth at night and other science related facts.\n",
    "        The returned string is in a JSON format that contains the reference id.\n",
    "        Be sure to use the same format in your agent's response\n",
    "        You must refer to references by id number\n",
    "    \"\"\"\n",
    "    # Take the last 5 messages in the conversation\n",
    "    messages = project_client.agents.messages.list(thread.id, limit=5, order=ListSortOrder.DESCENDING)\n",
    "    # Reverse the order so the most recent message is last\n",
    "    messages = list(messages)\n",
    "    messages.reverse()\n",
    "    retrieval_result = agent_client.retrieve(\n",
    "        retrieval_request=KnowledgeAgentRetrievalRequest(\n",
    "            messages=[\n",
    "                    KnowledgeAgentMessage(\n",
    "                        role=m[\"role\"],\n",
    "                        content=[KnowledgeAgentMessageTextContent(text=m[\"content\"])]\n",
    "                    ) for m in messages if m[\"role\"] != \"system\"\n",
    "            ]\n",
    "        )\n",
    "    )\n",
    "\n",
    "    # Associate the retrieval results with the last message in the conversation\n",
    "    last_message = messages[-1]\n",
    "    retrieval_results[last_message.id] = retrieval_result\n",
    "\n",
    "    # Return the grounding response to the agent\n",
    "    return retrieval_result.response[0].content[0].text\n",
    "\n",
    "# https://learn.microsoft.com/en-us/azure/ai-services/agents/how-to/tools/function-calling\n",
    "functions = FunctionTool({ agentic_retrieval })\n",
    "toolset = ToolSet()\n",
    "toolset.add(functions)\n",
    "project_client.agents.enable_auto_function_calls(toolset)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6bf5b621",
   "metadata": {},
   "source": [
    "## Start a chat with the agent\n",
    "\n",
    "During the chat, you use the standard Azure AI agent tool calling APIs.  We send the message with questions, and the agent decides when to retrieve knowledge from your search index using agentic retrieval.\n",
    "\n",
    "The remaining cells take a closer look at output and show how to add another turn to the conversation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "f1fc04fc",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Agent response: Suburban belts exhibit larger December brightening than urban cores despite higher absolute light levels downtown primarily because of holiday light displays and activities concentrated in the suburbs\n",
      " Suburban areas, with more yard space and a prevalence of single-family homes, tend to put up more holiday lights around Christmas and New Year's, resulting in a significant increase in light intensity by 20 to 50 percent in December\n",
      " In contrast, central urban areas, though brighter overall, show smaller relative increases in brightness during the holidays\n",
      " This pattern reflects cultural traditions and patterns of energy consumption, with suburban lighting displays contributing more to December brightening [refs 1, 3, 5]\n",
      "\n",
      "\n",
      "Regarding the sharp visibility of the Phoenix nighttime street grid from space compared to the dimmer interstate stretches between Midwestern cities, the reason lies in urban layout and lighting distribution\n",
      " Phoenix and its metropolitan area are characterized by a regular grid of city blocks and streets that are well illuminated, especially at intersections with large commercial properties and transportation corridors like Grand Avenue\n",
      " This grid pattern, fueled by suburban growth and widespread personal automobile use, creates a distinct, brightly lit street network visible from orbit\n",
      " On the other hand, large stretches of interstate highways in the Midwest pass through more rural or sparsely populated areas with less continuous urban development and fewer sources of lighting alongside the roadways, resulting in these stretches appearing comparatively dimmer in nighttime satellite images [refs 0, 2, 4, 6]\n",
      "\n"
     ]
    }
   ],
   "source": [
    "from azure.ai.agents.models import AgentsNamedToolChoice, AgentsNamedToolChoiceType, FunctionName\n",
    "\n",
    "message = project_client.agents.messages.create(\n",
    "    thread_id=thread.id,\n",
    "    role=\"user\",\n",
    "    content=\"\"\"\n",
    "        Why do suburban belts display larger December brightening than urban cores even though absolute light levels are higher downtown?\n",
    "        Why is the Phoenix nighttime street grid is so sharply visible from space, whereas large stretches of the interstate between midwestern cities remain comparatively dim?\n",
    "    \"\"\"\n",
    ")\n",
    "\n",
    "run = project_client.agents.runs.create_and_process(\n",
    "    thread_id=thread.id,\n",
    "    agent_id=agent.id,\n",
    "    tool_choice=AgentsNamedToolChoice(type=AgentsNamedToolChoiceType.FUNCTION, function=FunctionName(name=\"agentic_retrieval\")),\n",
    "    toolset=toolset)\n",
    "if run.status == \"failed\":\n",
    "    raise RuntimeError(f\"Run failed: {run.last_error}\")\n",
    "output = project_client.agents.messages.get_last_message_text_by_role(thread_id=thread.id, role=\"assistant\").text.value\n",
    "\n",
    "print(\"Agent response:\", output.replace(\".\", \"\\n\"))\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aa88be35",
   "metadata": {},
   "source": [
    "## Review retrieval activity and results\n",
    "\n",
    "Each retrieval response from Azure AI Search includes the unified string (grounding data from search search results), the query plan, and  reference data showing which chunks of source document contributed content to the unified string."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "7b90fefa",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Retrieval activity\n",
      "[\n",
      "  {\n",
      "    \"id\": 0,\n",
      "    \"type\": \"modelQueryPlanning\",\n",
      "    \"elapsed_ms\": 2342,\n",
      "    \"input_tokens\": 2256,\n",
      "    \"output_tokens\": 117\n",
      "  },\n",
      "  {\n",
      "    \"id\": 1,\n",
      "    \"type\": \"searchIndex\",\n",
      "    \"elapsed_ms\": 1145,\n",
      "    \"knowledge_source_name\": \"earth-at-night-ks\",\n",
      "    \"query_time\": \"2025-09-09T03:52:26.409Z\",\n",
      "    \"count\": 3,\n",
      "    \"search_index_arguments\": {\n",
      "      \"search\": \"Why do suburban belts display larger December brightening than urban cores despite higher absolute light levels downtown?\"\n",
      "    }\n",
      "  },\n",
      "  {\n",
      "    \"id\": 2,\n",
      "    \"type\": \"searchIndex\",\n",
      "    \"elapsed_ms\": 674,\n",
      "    \"knowledge_source_name\": \"earth-at-night-ks\",\n",
      "    \"query_time\": \"2025-09-09T03:52:27.094Z\",\n",
      "    \"count\": 4,\n",
      "    \"search_index_arguments\": {\n",
      "      \"search\": \"Why is the Phoenix nighttime street grid sharply visible from space compared to dimmer stretches of interstate between Midwestern cities?\"\n",
      "    }\n",
      "  },\n",
      "  {\n",
      "    \"id\": 3,\n",
      "    \"type\": \"semanticReranker\",\n",
      "    \"input_tokens\": 46720\n",
      "  }\n",
      "]\n",
      "Retrieval results\n",
      "[\n",
      "  {\n",
      "    \"type\": \"searchIndex\",\n",
      "    \"id\": \"0\",\n",
      "    \"activity_source\": 2,\n",
      "    \"source_data\": {\n",
      "      \"id\": \"earth_at_night_508_page_105_verbalized\",\n",
      "      \"page_chunk\": \"# Urban Structure\\n\\n## March 16, 2013\\n\\n### Phoenix Metropolitan Area at Night\\n\\nThis figure presents a nighttime satellite view of the Phoenix metropolitan area, highlighting urban structure and transport corridors. City lights illuminate the layout of several cities and major thoroughfares.\\n\\n**Labeled Urban Features:**\\n\\n- **Phoenix:** Central and brightest area in the right-center of the image.\\n- **Glendale:** Located to the west of Phoenix, this city is also brightly lit.\\n- **Peoria:** Further northwest, this area is labeled and its illuminated grid is seen.\\n- **Grand Avenue:** Clearly visible as a diagonal, brightly lit thoroughfare running from Phoenix through Glendale and Peoria.\\n- **Salt River Channel:** Identified in the southeast portion, running through illuminated sections.\\n- **Phoenix Mountains:** Dark, undeveloped region to the northeast of Phoenix.\\n- **Agricultural Fields:** Southwestern corner of the image, grid patterns are visible but with much less illumination, indicating agricultural land use.\\n\\n**Additional Notes:**\\n\\n- The overall pattern shows a grid-like urban development typical of western U.S. cities, with scattered bright nodes at major intersections or city centers.\\n- There is a clear transition from dense urban development to sparsely populated or agricultural land, particularly evident towards the bottom and left of the image.\\n- The illuminated areas follow the existing road and street grids, showcasing the extensive spread of the metropolitan area.\\n\\n**Figure Description:**  \\nA satellite nighttime image captured on March 16, 2013, showing Phoenix and surrounding areas (including Glendale and Peoria). Major landscape and infrastructural features, such as the Phoenix Mountains, Grand Avenue, the Salt River Channel, and agricultural fields, are labeled. The image reveals the extent of urbanization and the characteristic street grid illuminated by city lights.\\n\\n---\\n\\nPage 89\",\n",
      "      \"page_number\": 105\n",
      "    },\n",
      "    \"reranker_score\": 2.4687855,\n",
      "    \"doc_key\": \"earth_at_night_508_page_105_verbalized\"\n",
      "  },\n",
      "  {\n",
      "    \"type\": \"searchIndex\",\n",
      "    \"id\": \"2\",\n",
      "    \"activity_source\": 2,\n",
      "    \"source_data\": {\n",
      "      \"id\": \"earth_at_night_508_page_104_verbalized\",\n",
      "      \"page_chunk\": \"<!-- PageHeader=\\\"Urban Structure\\\" -->\\n\\n### Location of Phoenix, Arizona\\n\\nThe image depicts a globe highlighting the location of Phoenix, Arizona, in the southwestern United States, marked with a blue pinpoint on the map of North America. Phoenix is situated in the central part of Arizona, which is in the southwestern region of the United States.\\n\\n---\\n\\n### Grid of City Blocks-Phoenix, Arizona\\n\\nLike many large urban areas of the central and western United States, the Phoenix metropolitan area is laid out along a regular grid of city blocks and streets. While visible during the day, this grid is most evident at night, when the pattern of street lighting is clearly visible from the low-Earth-orbit vantage point of the ISS.\\n\\nThis astronaut photograph, taken on March 16, 2013, includes parts of several cities in the metropolitan area, including Phoenix (image right), Glendale (center), and Peoria (left). While the major street grid is oriented north-south, the northwest-southeast oriented Grand Avenue cuts across the three cities at image center. Grand Avenue is a major transportation corridor through the western metropolitan area; the lighting patterns of large industrial and commercial properties are visible along its length. Other brightly lit properties include large shopping centers, strip malls, and gas stations, which tend to be located at the intersections of north-south and east-west trending streets.\\n\\nThe urban grid encourages growth outwards along a city's borders by providing optimal access to new real estate. Fueled by the adoption of widespread personal automobile use during the twentieth century, the Phoenix metropolitan area today includes 25 other municipalities (many of them largely suburban and residential) linked by a network of surface streets and freeways.\\n\\nWhile much of the land area highlighted in this image is urbanized, there are several noticeably dark areas. The Phoenix Mountains are largely public parks and recreational land. To the west, agricultural fields provide a sharp contrast to the lit streets of residential developments. The Salt River channel appears as a dark ribbon within the urban grid.\\n\\n\\n<!-- PageFooter=\\\"Earth at Night\\\" -->\\n<!-- PageNumber=\\\"88\\\" -->\",\n",
      "      \"page_number\": 104\n",
      "    },\n",
      "    \"reranker_score\": 2.434402,\n",
      "    \"doc_key\": \"earth_at_night_508_page_104_verbalized\"\n",
      "  },\n",
      "  {\n",
      "    \"type\": \"searchIndex\",\n",
      "    \"id\": \"1\",\n",
      "    \"activity_source\": 1,\n",
      "    \"source_data\": {\n",
      "      \"id\": \"earth_at_night_508_page_174_verbalized\",\n",
      "      \"page_chunk\": \"<!-- PageHeader=\\\"Holiday Lights\\\" -->\\n\\n## Holiday Lights\\n\\n### Bursting with Holiday Energy-United States\\n\\nNASA researchers found that nighttime lights in the United States shine 20 to 50 percent brighter in December due to holiday light displays and other activities during Christmas and New Year's when compared to light output during the rest of the year.\\n\\nThe next five maps (see also pages 161-163), created using data from the VIIRS DNB on the Suomi NPP satellite, show changes in lighting intensity and location around many major cities, comparing the nighttime light signals from December 2012 and beyond.\\n\\n---\\n\\n#### Figure 1. Location Overview\\n\\nA map of the western hemisphere with a marker indicating the mid-Atlantic region of the eastern United States, where the study of holiday lighting intensity was focused.\\n\\n---\\n\\n#### Figure 2. Holiday Lighting Intensity: Mid-Atlantic United States (2012\\u20132014)\\n\\nA map showing Maryland, New Jersey, Delaware, Virginia, West Virginia, Ohio, Kentucky, Tennessee, North Carolina, South Carolina, and surrounding areas. Major cities labeled include Washington, D.C., Richmond, Norfolk, and Raleigh.\\n\\nThe map uses colors to indicate changes in holiday nighttime lighting intensity between 2012 and 2014:\\n\\n- **Green/bright areas**: More holiday lighting (areas shining 20\\u201350% brighter in December).\\n- **Yellow areas**: No change in lighting.\\n- **Dim/grey areas**: Less holiday lighting.\\n\\nKey observations from the map:\\n\\n- The Washington, D.C. metropolitan area shows significant increases in lighting during the holidays, extending into Maryland and Virginia.\\n- Urban centers such as Richmond (Virginia), Norfolk (Virginia), Raleigh (North Carolina), and clusters in Tennessee and South Carolina also experience notable increases in light intensity during December.\\n- Rural areas and the interiors of West Virginia, Kentucky, and North Carolina show little change or less holiday lighting, corresponding to population density and urbanization.\\n\\n**Legend:**\\n\\n| Holiday Lighting Change | Color on Map   |\\n|------------------------|---------------|\\n| More                   | Green/bright  |\\n| No Change              | Yellow        |\\n| Less                   | Dim/grey      |\\n\\n_The scale bar indicates a distance of 100 km for reference._\\n\\n---\\n\\n<!-- PageFooter=\\\"158 Earth at Night\\\" -->\",\n",
      "      \"page_number\": 174\n",
      "    },\n",
      "    \"reranker_score\": 2.1872926,\n",
      "    \"doc_key\": \"earth_at_night_508_page_174_verbalized\"\n",
      "  },\n",
      "  {\n",
      "    \"type\": \"searchIndex\",\n",
      "    \"id\": \"4\",\n",
      "    \"activity_source\": 2,\n",
      "    \"source_data\": {\n",
      "      \"id\": \"earth_at_night_508_page_124_verbalized\",\n",
      "      \"page_chunk\": \"# Urban Development\\n\\n## Figure: Location Highlight on Globe\\n\\nThis figure depicts a globe focused on North America, with a marker pinpointing the central region of the United States. The highlighted location represents the geographical focus of the text discussion on US urban development and transportation networks.\\n\\n---\\n\\n## Urban Development\\n\\n### Lighting Paths\\u2014Across the United States\\n\\nThe United States has more miles of roads than any other nation in the world\\u20144.1 million miles (6.6 million kilometers) to be precise, which is roughly 40 percent more than second-ranked India. About 47,000 miles (75,639 kilometers) of those roads are part of the Interstate Highway System, established by President Dwight Eisenhower in the 1950s. The country also has 127,000 miles (204,000 kilometers) of railroad tracks and about 25,000 miles (40,000 kilometers) of navigable rivers and canals (not including the Great Lakes). The imprint of that transportation web becomes easy to see at night.\\n\\nThe VIIRS DNB on the Suomi NPP satellite acquired this nighttime view (top image, right) of the continental United States on October 1, 2013. The roadway map (bottom image, right) traces the path of the major interstate highways, railroads, and rivers of the United States. Comparing the two images, you quickly see how the cities and settlements align with the transportation corridors. In the early days of the republic, post roads and toll roads for horse-drawn carts and carriages were built to connect eastern cities like Boston, New York, Baltimore, and Philadelphia, though relatively few travelers made the long, unlit journeys. Railroads became the dominant transportation method for people and cargo in the middle of the nineteenth century, establishing longer links across the Nation and waypoints across the Midwest, the Great Plains, and the Rockies. Had nighttime satellite images existed in that era, they probably would show only dim pearls of light around major cities in the east and scattered across the country; the strands of steel tracks and cobbled roads that connected them would be invisible from space.\\n\\nEventually, cars and trucks became the dominant form of transportation in the United States. Drivers then needed roads and lighting to keep them safe on those roads. As the Nation grew in the twentieth century, the development of new cities and suburbs often conformed to the path of the interstate highways, adding light along the paths between the cities.\\n\\nOver the years, the length of navigable rivers has been a constant, as is their relative lack of light. Even today the only light seems to be the occasional port cities along riverbanks and the light of ships themselves.\\n\\n---\\n\\n**Table: Summary of U.S. Transportation Infrastructure**\\n\\n| Infrastructure Type     | Total Mileage (mi) | Total Mileage (km) |\\n|------------------------|--------------------|--------------------|\\n| Roads (All)            | 4,100,000          | 6,600,000          |\\n| Interstate Highways    | 47,000             | 75,639             |\\n| Railroads              | 127,000            | 204,000            |\\n| Navigable Rivers/Canals| 25,000             | 40,000             |\\n\\n---\\n\\n<!-- PageFooter=\\\"108 Earth at Night\\\" -->\",\n",
      "      \"page_number\": 124\n",
      "    },\n",
      "    \"reranker_score\": 2.0973017,\n",
      "    \"doc_key\": \"earth_at_night_508_page_124_verbalized\"\n",
      "  },\n",
      "  {\n",
      "    \"type\": \"searchIndex\",\n",
      "    \"id\": \"6\",\n",
      "    \"activity_source\": 2,\n",
      "    \"source_data\": {\n",
      "      \"id\": \"earth_at_night_508_page_125_verbalized\",\n",
      "      \"page_chunk\": \"# Urban Development\\n\\n**Date:** October 1, 2013\\n\\n---\\n\\n## Figure: Urban Development and Infrastructure in the United States\\n\\nThis figure comprises two maps of the continental United States, highlighting the patterns of urban development and infrastructure.\\n\\n### Top Panel: Nighttime Lights Map (October 1, 2013)\\n\\nThis map displays the United States as seen from space at night on October 1, 2013. Major observations include:\\n\\n- A dense concentration of bright spots representing urban and suburban areas with prominent lighting, especially along the east coast, the Midwest (notably around Chicago), Texas, and California.\\n- The west and central parts of the country, such as the Rocky Mountains and deserts, appear much darker, indicating sparse population and fewer urban centers.\\n- The boundaries of the United States are outlined for reference.\\n- Major urban corridors are clearly visible, including the heavily lit regions running from Boston through New York City, Philadelphia, Baltimore, D.C., Atlanta, and further south, as well as the line of cities from Los Angeles through southern California.\\n\\n### Bottom Panel: Major Transport and River Networks\\n\\nThis map outlines the primary interstate highways, railroad lines, and major river systems in the continental United States, using different colors to distinguish among them:\\n\\n| Feature    | Color       | Description                                                                       |\\n|------------|-------------|-----------------------------------------------------------------------------------|\\n| Interstate | Red         | Key high-speed roadways, forming a vast national network and connecting cities     |\\n| Railroad   | Green       | Major rail lines paralleling some highway routes, providing freight and passenger service |\\n| River      | Blue        | Major river systems used historically for transport, industry, and urban siting    |\\n\\n- The locations of interstate highways closely follow the distribution of nighttime lights, as seen in the top panel.\\n- Railroad networks are especially dense in the Midwest and northeast, regions with both high population density and industrial activity.\\n- Major rivers, such as the Mississippi, Missouri, and Ohio, are marked in blue, reflecting their importance for historical urban development.\\n\\n**Scale:** Both maps include a scale bar representing 500 km and a North arrow for orientation.\\n\\n---\\n\\n**Summary:**  \\nThe figure visually demonstrates the relationship between urban development (as observed through nighttime satellite imagery) and the underlying networks of interstates, railroads, and rivers that have historically influenced the growth and connectivity of American cities. Most urbanized and densely lit areas correspond to nodes and crossroads within this transportation and river network.\\n\\n---\\n\\n**Page 109**\",\n",
      "      \"page_number\": 125\n",
      "    },\n",
      "    \"reranker_score\": 2.0677037,\n",
      "    \"doc_key\": \"earth_at_night_508_page_125_verbalized\"\n",
      "  },\n",
      "  {\n",
      "    \"type\": \"searchIndex\",\n",
      "    \"id\": \"3\",\n",
      "    \"activity_source\": 1,\n",
      "    \"source_data\": {\n",
      "      \"id\": \"earth_at_night_508_page_176_verbalized\",\n",
      "      \"page_chunk\": \"# Holiday Lights\\n\\n## Figure 1: Location Marker on Globe\\n\\n**Description:**  \\nA world map focused on the Western Hemisphere, with a marker placed in the eastern United States. This image serves to indicate the geographic focus of the following data and discussion about holiday lighting patterns, particularly those observed in the United States.\\n\\n---\\n\\nHoliday lights increase most dramatically in the suburbs and outskirts of major cities, where there is more yard space and a prevalence of single-family homes. Central urban areas do not see as large an increase in lighting, but they still experience a brightening of 20 to 30 percent during the holidays. This pattern holds true across the U.S., which remains ethnically and religiously diverse but participates in a nationally shared tradition of increased holiday lighting during holiday seasons.\\n\\nBeyond the cultural implications, this trend has significant consequences for energy consumption. The availability of a daily, global dynamic dataset of nighttime lights offers new insights into the broad societal forces influencing energy decisions. As noted by the Intergovernmental Panel on Climate Change, improvements in energy efficiency and conservation are essential to reducing greenhouse gas emissions. Examining daily nightlight data provides a valuable perspective on urban and suburban life, helping to reveal the underlying patterns and drivers of energy use.\\n\\n*(Images continue on pages 161-163)*\\n\\n---\\n\\n*Page 160 Earth at Night*\",\n",
      "      \"page_number\": 176\n",
      "    },\n",
      "    \"reranker_score\": 2.0156853,\n",
      "    \"doc_key\": \"earth_at_night_508_page_176_verbalized\"\n",
      "  },\n",
      "  {\n",
      "    \"type\": \"searchIndex\",\n",
      "    \"id\": \"5\",\n",
      "    \"activity_source\": 1,\n",
      "    \"source_data\": {\n",
      "      \"id\": \"earth_at_night_508_page_175_verbalized\",\n",
      "      \"page_chunk\": \"# Holiday Lights\\n\\nFrom 2013 to the average light output for the rest of 2012 to 2014, the change in light usage is subtle on any given night. However, when averaged over days and weeks, the pattern becomes more perceptible. Areas where light usage increased in December are marked in green, areas with little change are marked in yellow, and areas where less light was used are marked in red.\\n\\nThe light output from 70 U.S. cities was examined as a first step toward determining patterns in urban energy use. Researchers found that light intensity increased by 30 to 50 percent in December in many areas, which may be related to holiday lighting.\\n\\n---\\n\\n## Figure 1: Location Reference\\n\\nA globe highlights the southeastern region of the United States, pinpointing the area of interest for the study of holiday light usage, focusing on states like Tennessee, North Carolina, South Carolina, Georgia, and Alabama.\\n\\n---\\n\\n## Figure 2: Holiday Lighting Patterns in the Southeastern United States (2012\\u20132014)\\n\\nThis map highlights several cities in the southeastern United States, including Nashville, Charlotte, Columbia, Birmingham, and Atlanta. The states of Tennessee, North Carolina, South Carolina, Alabama, and Georgia are outlined, along with the Atlantic Ocean to the east.\\n\\n### Key Observations:\\n- The most significant concentrations of nighttime lighting are seen in major metropolitan areas, with Atlanta having the largest and most intense area of light.\\n- Other notable clusters of increased light output are visible in Nashville, Charlotte, Birmingham, and Columbia.\\n- The map reflects changes in light usage during December of 2012\\u20132014, with \\u201cmore\\u201d lighting (green shading) concentrated around urban areas, indicating an increase due to holiday lighting displays.\\n\\n**Map Details:**\\n- Time frame: 2012\\u20132014\\n- Locations marked: Nashville (Tennessee), Charlotte (North Carolina), Columbia (South Carolina), Birmingham (Alabama), Atlanta (Georgia)\\n- Scale: 100 km bar provided\\n- North directional arrow included\\n\\n---\\n\\n### Legend:\\n- **Green Shading**: Areas where light usage increased in December (likely due to holiday lights)\\n- **Yellow Shading**: Areas with little change in light usage\\n- **Red Shading**: Areas where less light was used\\n\\n---\\n\\n#### Page Footer: \\u201cno change\\u201d\\n#### Page Number: 159\",\n",
      "      \"page_number\": 175\n",
      "    },\n",
      "    \"reranker_score\": 1.9665027,\n",
      "    \"doc_key\": \"earth_at_night_508_page_175_verbalized\"\n",
      "  }\n",
      "]\n"
     ]
    }
   ],
   "source": [
    "import json\n",
    "\n",
    "retrieval_result = retrieval_results.get(message.id)\n",
    "if retrieval_result is None:\n",
    "    raise RuntimeError(f\"No retrieval results found for message {message.id}\")\n",
    "\n",
    "print(\"Retrieval activity\")\n",
    "print(json.dumps([activity.as_dict() for activity in retrieval_result.activity], indent=2))\n",
    "print(\"Retrieval results\")\n",
    "print(json.dumps([reference.as_dict() for reference in retrieval_result.references], indent=2))\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4b6bfb9f",
   "metadata": {},
   "source": [
    "## Continue the conversation..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "id": "d9478191",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Agent response: To find lava at night, satellite instruments can be used to detect the thermal infrared signature emitted by the hot lava flows\n",
      " For example, during eruptions such as those at Mount Etna in Italy and Kilauea in Hawaii, satellites like Landsat 8 use instruments such as the Operational Land Imager (OLI) and the Thermal Infrared Sensor (TIRS) to capture images that highlight active vents and flowing lava by their heat emission\n",
      " These thermal infrared images show very hot lava as bright white or red, distinguishing it clearly from cooler surroundings and city lights\n",
      "\n",
      "\n",
      "Additionally, the VIIRS Day/Night Band (DNB) on polar-orbiting satellites can detect faint light sources including the glow from lava flows at night, often combined with moonlight to enhance visibility\n",
      " Nighttime glow from lava can thus be observed as bright spots different from city lights in satellite images, making it possible to monitor volcanic activity even in darkness\n",
      " This technique is used to track lava flows and volcanic eruptions for scientific research and public safety\n",
      "\n",
      "\n",
      "In summary, finding lava at night relies on satellite thermal infrared imaging to see the heat emitted by lava and enhanced night light detection capabilities to distinguish the glowing lava from other nighttime lights [refs 0, 1, 2, 4, 6]\n",
      "\n"
     ]
    }
   ],
   "source": [
    "message = project_client.agents.messages.create(\n",
    "    thread_id=thread.id,\n",
    "    role=\"user\",\n",
    "    content=\"How do I find lava at night? Use the retrieval tool to answer this question.\"\n",
    ")\n",
    "\n",
    "run = project_client.agents.runs.create_and_process(\n",
    "    thread_id=thread.id,\n",
    "    agent_id=agent.id,\n",
    "    tool_choice=AgentsNamedToolChoice(type=AgentsNamedToolChoiceType.FUNCTION, function=FunctionName(name=\"agentic_retrieval\")),\n",
    "    toolset=toolset)\n",
    "if run.status == \"failed\":\n",
    "    raise RuntimeError(f\"Run failed: {run.last_error}\")\n",
    "output = project_client.agents.messages.get_last_message_text_by_role(thread_id=thread.id, role=\"assistant\").text.value\n",
    "\n",
    "\n",
    "print(\"Agent response:\", output.replace(\".\", \"\\n\"))\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b366ed37",
   "metadata": {},
   "source": [
    "## Review retrieval activity and results\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "id": "c063c45e",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Retrieval activity\n",
      "[\n",
      "  {\n",
      "    \"id\": 0,\n",
      "    \"type\": \"modelQueryPlanning\",\n",
      "    \"elapsed_ms\": 1694,\n",
      "    \"input_tokens\": 2662,\n",
      "    \"output_tokens\": 74\n",
      "  },\n",
      "  {\n",
      "    \"id\": 1,\n",
      "    \"type\": \"searchIndex\",\n",
      "    \"elapsed_ms\": 617,\n",
      "    \"knowledge_source_name\": \"earth-at-night-ks\",\n",
      "    \"query_time\": \"2025-09-09T03:53:13.369Z\",\n",
      "    \"count\": 17,\n",
      "    \"search_index_arguments\": {\n",
      "      \"search\": \"How to find lava at night\"\n",
      "    }\n",
      "  },\n",
      "  {\n",
      "    \"id\": 2,\n",
      "    \"type\": \"searchIndex\",\n",
      "    \"elapsed_ms\": 631,\n",
      "    \"knowledge_source_name\": \"earth-at-night-ks\",\n",
      "    \"query_time\": \"2025-09-09T03:53:14.001Z\",\n",
      "    \"count\": 16,\n",
      "    \"search_index_arguments\": {\n",
      "      \"search\": \"Methods to locate lava flows during nighttime\"\n",
      "    }\n",
      "  },\n",
      "  {\n",
      "    \"id\": 3,\n",
      "    \"type\": \"semanticReranker\",\n",
      "    \"input_tokens\": 44714\n",
      "  }\n",
      "]\n",
      "Retrieval results\n",
      "[\n",
      "  {\n",
      "    \"type\": \"searchIndex\",\n",
      "    \"id\": \"0\",\n",
      "    \"activity_source\": 2,\n",
      "    \"source_data\": {\n",
      "      \"id\": \"earth_at_night_508_page_46_verbalized\",\n",
      "      \"page_chunk\": \"For the first time in perhaps a decade, Mount Etna experienced a \\\"flank eruption\\\"\\u2014erupting from its side instead of its summit\\u2014on December 24, 2018. The activity was accompanied by 130 earthquakes occurring over three hours that morning. Mount Etna, Europe\\u2019s most active volcano, has seen periodic activity on this part of the mountain since 2013. The Operational Land Imager (OLI) on the Landsat 8 satellite acquired the main image of Mount Etna on December 28, 2018.\\n\\nThe inset image highlights the active vent and thermal infrared signature from lava flows, which can be seen near the newly formed fissure on the southeastern side of the volcano. The inset was created with data from OLI and the Thermal Infrared Sensor (TIRS) on Landsat 8. Ash spewing from the fissure cloaked adjacent villages and delayed aircraft from landing at the nearby Catania airport. Earthquakes occurred in the subsequent days after the initial eruption and displaced hundreds of people from their homes.\\n\\nFor nighttime images of Mount Etna\\u2019s March 2017 eruption, see pages 48\\u201351.\\n\\n---\\n\\n### Hazards of Volcanic Ash Plumes and Satellite Observation\\n\\nWith the help of moonlight, satellite instruments can track volcanic ash plumes, which present significant hazards to airplanes in flight. The volcanic ash\\u2014composed of tiny pieces of glass and rock\\u2014is abrasive to engine turbine blades, and can melt on the blades and other engine parts, causing damage and even engine stalls. This poses a danger to both the plane\\u2019s integrity and passenger safety. Volcanic ash also reduces visibility for pilots and can cause etching of windshields, further reducing pilots\\u2019 ability to see. Nightlight images can be combined with thermal images to provide a more complete view of volcanic activity on Earth\\u2019s surface.\\n\\nThe VIIRS Day/Night Band (DNB) on polar-orbiting satellites uses faint light sources such as moonlight, airglow (the atmosphere\\u2019s self-illumination through chemical reactions), zodiacal light (sunlight scattered by interplanetary dust), and starlight from the Milky Way. Using these dim light sources, the DNB can detect changes in clouds, snow cover, and sea ice:\\n\\n#### Table: Light Sources Used by VIIRS DNB\\n\\n| Light Source         | Description                                                                  |\\n|----------------------|------------------------------------------------------------------------------|\\n| Moonlight            | Reflected sunlight from the Moon, illuminating Earth's surface at night      |\\n| Airglow              | Atmospheric self-illumination from chemical reactions                        |\\n| Zodiacal Light       | Sunlight scattered by interplanetary dust                                    |\\n| Starlight/Milky Way  | Faint illumination provided by stars in the Milky Way                        |\\n\\nGeostationary Operational Environmental Satellites (GOES), managed by NOAA, orbit over Earth\\u2019s equator and offer uninterrupted observations of North America. High-latitude areas such as Alaska benefit from polar-orbiting satellites like Suomi NPP, which provide overlapping coverage at the poles, enabling more data collection in these regions. During polar darkness (winter months), VIIRS DNB data allow scientists to:\\n\\n- Observe sea ice formation\\n- Monitor snow cover extent at the highest latitudes\\n- Detect open water for ship navigation\\n\\n#### Table: Satellite Coverage Overview\\n\\n| Satellite Type          | Orbit           | Coverage Area         | Special Utility                              |\\n|------------------------|-----------------|----------------------|----------------------------------------------|\\n| GOES                   | Geostationary   | Equatorial/North America | Continuous regional monitoring              |\\n| Polar-Orbiting (e.g., Suomi NPP) | Polar-orbiting    | Poles/high latitudes      | Overlapping passes; useful during polar night|\\n\\n---\\n\\n### Weather Forecasting and Nightlight Data\\n\\nThe use of nightlight data by weather forecasters is growing as the VIIRS instrument enables observation of clouds at night illuminated by sources such as moonlight and lightning. Scientists use these data to study the nighttime behavior of weather systems, including severe storms, which can develop and strike populous areas at night as well as during the day. Combined with thermal data, visible nightlight data allow the detection of clouds at various heights in the atmosphere, such as dense marine fog. This capability enables weather forecasters to issue marine advisories with higher confidence, leading to greater utility. (See \\\"Marine Layer Clouds\\u2014California\\\" on page 56.)\\n\\nIn this section of the book, you will see how nightlight data are used to observe nature\\u2019s spectacular light shows across a wide range of sources.\\n\\n---\\n\\n#### Notable Data from Mount Etna Flank Eruption (December 2018)\\n\\n| Event/Observation                  | Details                                                                    |\\n|-------------------------------------|----------------------------------------------------------------------------|\\n| Date of Flank Eruption              | December 24, 2018                                                          |\\n| Number of Earthquakes               | 130 earthquakes within 3 hours                                              |\\n| Image Acquisition                   | December 28, 2018 by Landsat 8 OLI                                         |\\n| Location of Eruption                | Southeastern side of Mount Etna                                            |\\n| Thermal Imaging Data                | From OLI and TIRS (Landsat 8), highlighting active vent and lava flows     |\\n| Impact on Villages/Air Transport    | Ash covered villages; delayed aircraft at Catania airport                  |\\n| Displacement                        | Hundreds of residents displaced                                            |\\n| Ongoing Seismic Activity            | Earthquakes continued after initial eruption                               |\\n\\n---\\n\\n<!-- PageFooter=\\\"Earth at Night\\\" -->\\n<!-- PageNumber=\\\"30\\\" -->\",\n",
      "      \"page_number\": 46\n",
      "    },\n",
      "    \"reranker_score\": 2.6578948,\n",
      "    \"doc_key\": \"earth_at_night_508_page_46_verbalized\"\n",
      "  },\n",
      "  {\n",
      "    \"type\": \"searchIndex\",\n",
      "    \"id\": \"1\",\n",
      "    \"activity_source\": 1,\n",
      "    \"source_data\": {\n",
      "      \"id\": \"earth_at_night_508_page_64_verbalized\",\n",
      "      \"page_chunk\": \"<!-- PageHeader=\\\"Volcanoes\\\" -->\\n\\n### Nighttime Glow at Mount Etna - Italy\\n\\nAt about 2:30 a.m. local time on March 16, 2017, the VIIRS DNB on the Suomi NPP satellite captured this nighttime image of lava flowing on Mount Etna in Sicily, Italy. Etna is one of the world's most active volcanoes.\\n\\n#### Figure: Location of Mount Etna\\nA world globe is depicted, with a marker indicating the location of Mount Etna in Sicily, Italy, in southern Europe near the center of the Mediterranean Sea.\\n\\n<!-- PageFooter=\\\"Earth at Night\\\" -->\\n<!-- PageNumber=\\\"48\\\" -->\",\n",
      "      \"page_number\": 64\n",
      "    },\n",
      "    \"reranker_score\": 2.6323729,\n",
      "    \"doc_key\": \"earth_at_night_508_page_64_verbalized\"\n",
      "  },\n",
      "  {\n",
      "    \"type\": \"searchIndex\",\n",
      "    \"id\": \"2\",\n",
      "    \"activity_source\": 2,\n",
      "    \"source_data\": {\n",
      "      \"id\": \"earth_at_night_508_page_60_verbalized\",\n",
      "      \"page_chunk\": \"<!-- PageHeader=\\\"Volcanoes\\\" -->\\n\\n## Volcanoes\\n\\n### The Infrared Glows of Kilauea's Lava Flows\\u2014Hawaii\\n\\nIn early May 2018, an eruption on Hawaii's Kilauea volcano began to unfold. The eruption took a dangerous turn on May 3, 2018, when new fissures opened in the residential neighborhood of Leilani Estates. During the summer-long eruptive event, other fissures emerged along the East Rift Zone. Lava from vents along the rift zone flowed downslope, reaching the ocean in several areas, and filling in Kapoho Bay.\\n\\nA time series of Landsat 8 imagery shows the progression of the lava flows from May 16 to August 13. The night view combines thermal, shortwave infrared, and near-infrared wavelengths to tease out the very hot lava (bright white), cooling lava (red), and lava flows obstructed by clouds (purple).\\n\\n#### Figure: Location of Kilauea Volcano, Hawaii\\n\\nA globe is shown centered on North America, with a marker placed in the Pacific Ocean indicating the location of Hawaii, to the southwest of the mainland United States.\\n\\n<!-- PageFooter=\\\"Earth at Night\\\" -->\\n<!-- PageNumber=\\\"44\\\" -->\",\n",
      "      \"page_number\": 60\n",
      "    },\n",
      "    \"reranker_score\": 2.6274104,\n",
      "    \"doc_key\": \"earth_at_night_508_page_60_verbalized\"\n",
      "  },\n",
      "  {\n",
      "    \"type\": \"searchIndex\",\n",
      "    \"id\": \"3\",\n",
      "    \"activity_source\": 1,\n",
      "    \"source_data\": {\n",
      "      \"id\": \"earth_at_night_508_page_44_verbalized\",\n",
      "      \"page_chunk\": \"## Nature's Light Shows\\n\\nAt night, with the light of the Sun removed, nature's brilliant glow from Earth's surface becomes visible to the naked eye from space. Some of Earth's most spectacular light shows are natural, like the aurora borealis, or Northern Lights, in the Northern Hemisphere (aurora australis, or Southern Lights, in the Southern Hemisphere). The auroras are natural electrical phenomena caused by charged particles that race from the Sun toward Earth, inducing chemical reactions in the upper atmosphere and creating the appearance of streamers of reddish or greenish light in the sky, usually near the northern or southern magnetic pole. Other natural lights can indicate danger, like a raging forest fire encroaching on a city, town, or community, or lava spewing from an erupting volcano.\\n\\nWhatever the source, the ability of humans to monitor nature's light shows at night has practical applications for society. For example, tracking fires during nighttime hours allows for continuous monitoring and enhances our ability to protect humans and other animals, plants, and infrastructure. Combined with other data sources, our ability to observe the light of fires at night allows emergency managers to more efficiently and accurately issue warnings and evacuation orders and allows firefighting efforts to continue through the night. With enough moonlight (e.g., full-Moon phase), it's even possible to track the movement of smoke plumes at night, which can impact air quality, regardless of time of day.\\n\\nAnother natural source of light at night is emitted from glowing lava flows at the site of active volcanoes. Again, with enough moonlight, these dramatic scenes can be tracked and monitored for both scientific research and public safety.\\n\\n\\n### Figure: The Northern Lights Viewed from Space\\n\\n**September 17, 2011**\\n\\nThis photo, taken from the International Space Station on September 17, 2011, shows a spectacular display of the aurora borealis (Northern Lights) as green and reddish light in the night sky above Earth. In the foreground, part of a Soyuz spacecraft is visible, silhouetted against the bright auroral light. The green glow is generated by energetic charged particles from the Sun interacting with Earth's upper atmosphere, exciting oxygen and nitrogen atoms, and producing characteristic colors. The image demonstrates the vividness and grandeur of natural night-time light phenomena as seen from orbit.\",\n",
      "      \"page_number\": 44\n",
      "    },\n",
      "    \"reranker_score\": 2.6054332,\n",
      "    \"doc_key\": \"earth_at_night_508_page_44_verbalized\"\n",
      "  },\n",
      "  {\n",
      "    \"type\": \"searchIndex\",\n",
      "    \"id\": \"4\",\n",
      "    \"activity_source\": 1,\n",
      "    \"source_data\": {\n",
      "      \"id\": \"earth_at_night_508_page_66_verbalized\",\n",
      "      \"page_chunk\": \"# Volcanoes\\n\\n---\\n\\n### Mount Etna Erupts - Italy\\n\\nThe highly active Mount Etna in Italy sent red lava rolling down its flank on March 19, 2017. An astronaut onboard the ISS took the photograph below of the volcano and its environs that night. City lights surround the mostly dark volcanic area.\\n\\n---\\n\\n#### Figure 1: Location of Mount Etna, Italy\\n\\nA world map highlighting the location of Mount Etna in southern Italy. The marker indicates its geographic placement on the east coast of Sicily, Italy, in the Mediterranean region, south of mainland Europe and north of northern Africa.\\n\\n---\\n\\n#### Figure 2: Nighttime View of Mount Etna's Eruption and Surrounding Cities\\n\\nThis is a nighttime satellite image taken on March 19, 2017, showing the eruption of Mount Etna (southeastern cone) with visible bright red and orange coloring indicating flowing lava from a lateral vent. The surrounding areas are illuminated by city lights, with the following geographic references labeled:\\n\\n| Location        | Position in Image         | Visible Characteristics                    |\\n|-----------------|--------------------------|--------------------------------------------|\\n| Mt. Etna (southeastern cone) | Top center-left | Bright red/orange lava flow                |\\n| Lateral vent    | Left of the volcano       | Faint red/orange flow extending outwards   |\\n| Resort          | Below the volcano, to the left   | Small cluster of lights                    |\\n| Giarre          | Top right                 | Bright cluster of city lights              |\\n| Acireale        | Center right              | Large, bright area of city lights          |\\n| Biancavilla     | Bottom left               | Smaller cluster of city lights             |\\n\\nAn arrow pointing north is shown on the image for orientation.\\n\\n---\\n\\n<!-- Earth at Night Page Footer -->\\n<!-- Page Number: 50 -->\",\n",
      "      \"page_number\": 66\n",
      "    },\n",
      "    \"reranker_score\": 2.595508,\n",
      "    \"doc_key\": \"earth_at_night_508_page_66_verbalized\"\n",
      "  },\n",
      "  {\n",
      "    \"type\": \"searchIndex\",\n",
      "    \"id\": \"6\",\n",
      "    \"activity_source\": 1,\n",
      "    \"source_data\": {\n",
      "      \"id\": \"earth_at_night_508_page_65_verbalized\",\n",
      "      \"page_chunk\": \"# Volcanoes\\n\\n## Figure: Satellite Image of Sicily and Mount Etna Lava, March 16, 2017\\n\\nThe annotated satellite image below shows the island of Sicily and the surrounding region at night, highlighting city lights and volcanic activity.\\n\\n**Description:**\\n\\n- **Date of image:** March 16, 2017\\n- **Geographical locations labeled:**\\n    - Major cities: Palermo (northwest Sicily), Marsala (western Sicily), Catania (eastern Sicily)\\n    - Significant feature: Mount Etna, labeled with an adjacent \\\"hot lava\\\" region showing the glow from active lava flows\\n    - Surrounding water body: Mediterranean Sea\\n    - Island: Malta to the south of Sicily\\n- **Other details:** \\n    - The image is shown at night, with bright spots indicating city lights.\\n    - The position of \\\"hot lava\\\" near Mount Etna is distinctly visible as a bright spot different from other city lights, indicating volcanic activity.\\n    - A scale bar is included showing a reference length of 50 km.\\n    - North direction is indicated with an arrow.\\n    - Cloud cover is visible in the southwest part of the image, partially obscuring the view near Marsala and Malta.\\n\\n**Summary of Features Visualized:**\\n\\n| Feature          | Description                                           |\\n|------------------|------------------------------------------------------|\\n| Cities           | Bright clusters indicating locations: Palermo, Marsala, Catania |\\n| Mount Etna       | Marked on the map, located on the eastern side of Sicily, with visible hot lava activity |\\n| Malta            | Clearly visible to the south of Sicily               |\\n| Water bodies     | Mediterranean Sea labeled                            |\\n| Scale & Direction| 50 km scale bar and North indicator                  |\\n| Date             | March 16, 2017                                       |\\n| Cloud Cover      | Visible in the lower left (southern) part of the image |\\n\\nThis figure demonstrates the visibility of volcanic activity at Mount Etna from space at night, distinguishing the light from hot lava against the background city lights of Sicily and Malta.\",\n",
      "      \"page_number\": 65\n",
      "    },\n",
      "    \"reranker_score\": 2.5714042,\n",
      "    \"doc_key\": \"earth_at_night_508_page_65_verbalized\"\n",
      "  },\n",
      "  {\n",
      "    \"type\": \"searchIndex\",\n",
      "    \"id\": \"5\",\n",
      "    \"activity_source\": 2,\n",
      "    \"source_data\": {\n",
      "      \"id\": \"earth_at_night_508_page_5_verbalized\",\n",
      "      \"page_chunk\": \"## Contents\\n\\n**Foreword** ............................................... X\\n\\n| Section                                                 | Page |\\n|---------------------------------------------------------|------|\\n| Preface                                                 | xii  |\\n| Acknowledgments                                         | xiv  |\\n| An Introduction to Nightlights                          | 2    |\\n| Blue Marble Becomes Black Marble                        | 4    |\\n| Vision and Remote Sensing                               | 6    |\\n| Seeing Is Sensing                                       | 6    |\\n| What Is Light?                                          | 6    |\\n| Remote Sensing.                                         | 8    |\\n| Orbiting Tools to Observe Nightlights.                  | 10   |\\n| Improvements in ISS Photography-Northeastern United States | 16   |\\n| Coming into Focus-Cairo, Egypt.                         | 18   |\\n| Where Do Nightlights Come From?                         | 20   |\\n| Beyond City Lights-Java Sea                             | 22   |\\n| Moonlight, Old Lights, and New Lights-Gulf of Mexico    | 24   |\\n| A World of Change                                       | 26   |\\n| Nature's Light Shows                                    | 28   |\\n| Fires.                                                  | 32   |\\n| Tracking Fires Day and Night-Northwest United States    | 32   |\\n| Progression of the Rim Fire-Yosemite, California        | 35   |\\n| Spreading Like Wildfire-Yakutia, Siberia, Russia.       | 36   |\\n| City Lights, or Not-Australia                           | 39   |\\n| Billowing Smoke in the Night-Idaho and Montana          | 40   |\\n| Fires Light Up Mount Vesuvius-Naples, Italy             | 42   |\\n| Volcanoes                                               | 44   |\\n| The Infrared Glows of Kilauea's Lava Flows-Hawaii       | 44   |\\n| Mount Tongariro Erupts-New Zealand                      | 46   |\\n\\n<!-- PageNumber=\\\"v\\\" -->\",\n",
      "      \"page_number\": 5\n",
      "    },\n",
      "    \"reranker_score\": 2.2034209,\n",
      "    \"doc_key\": \"earth_at_night_508_page_5_verbalized\"\n",
      "  },\n",
      "  {\n",
      "    \"type\": \"searchIndex\",\n",
      "    \"id\": \"7\",\n",
      "    \"activity_source\": 2,\n",
      "    \"source_data\": {\n",
      "      \"id\": \"earth_at_night_508_page_189_verbalized\",\n",
      "      \"page_chunk\": \"## Appendix B\\n\\n### Making a Cloud-Free, Global, Earth-at-Night Image Using NASA's Black Marble Product Suite\\n\\nIn its orbit, the Suomi National Polar-orbiting Partnership (NPP) satellite platform flies 512 miles (824 kilometers) above Earth, crossing the equator at roughly 1:30 a.m. and 1:30 p.m. local time, while circling the planet from pole to pole about 14 times a day. A key instrument on Suomi NPP is the Visible Infrared Imaging Radiometer Suite (VIIRS), which is a multispectral instrument that scans 1889-mile- (3040-kilometer-) wide swaths of data.\\n\\n---\\n\\n#### Figure 1. VIIRS instrument active scanning swath\\n\\nThis figure shows a global view of the Earth at night, with the VIIRS satellite positioned above the surface. The satellite is scanning a wide nighttime swath over North and South America, as depicted by a highlighted, rectangular region that stretches from near the North Pole to the South Pole, crossing over the United States and South America. The highlighted region represents the area being scanned by the VIIRS instrument, clearly showing the satellite\\u2019s orbital track and the data collection sweep across the globe. The visible areas include illuminated urban regions\\u2014clusters of light in the eastern United States and portions of South America\\u2014demonstrating the sensitivity of the instrument to city lights at night.\\n\\n---\\n\\n#### Figure 2. Nighttime swath\\n\\nThis figure presents a global map projection with a highlighted \\\"nighttime swath\\\" running north to south over the Americas and the Atlantic Ocean, as indicated by a white label and arrow. The background is a composite satellite image showing Earth's continents and cloud cover, with much of the image in daylight and a defined nighttime swath stretching vertically from North America through South America. Within the swath, city lights are visible, especially over the central and eastern United States and parts of South America, illustrating the data captured by VIIRS during nighttime hours. The figure contextualizes the satellite's path and the daily coverage achieved by its Earth-at-night observations.\\n\\n---\\n\\nThe Suomi NPP satellite observes Earth's surface throughout the day and at night. The Day/Night Band (DNB) of the VIIRS instrument detects light in a range of wavelengths from green (500 nanometers) to near-infrared (900 nanometers) and uses filtering techniques to observe dim signals such as city lights\\u2014down to the scale of an isolated highway lamp\\u2014wildfires, gas flares, auroras, and reflected moonlight at night. In this example (above), the satellite acquired a swath of data during nighttime hours over portions of South America, the Atlantic Ocean, and the Eastern United States.\",\n",
      "      \"page_number\": 189\n",
      "    },\n",
      "    \"reranker_score\": 2.118703,\n",
      "    \"doc_key\": \"earth_at_night_508_page_189_verbalized\"\n",
      "  },\n",
      "  {\n",
      "    \"type\": \"searchIndex\",\n",
      "    \"id\": \"8\",\n",
      "    \"activity_source\": 1,\n",
      "    \"source_data\": {\n",
      "      \"id\": \"earth_at_night_508_page_106_verbalized\",\n",
      "      \"page_chunk\": \"<!-- PageHeader=\\\"Urban Structure\\\" -->\\n\\n### Location of Naples, Italy\\n\\nThis globe highlights the location of Naples, Italy, in southern Europe. The marker indicates the city's position on the Italian peninsula, in proximity to the Mediterranean Sea.\\n\\n---\\n\\n### Unpopulated Slopes of an Active Volcano - Naples, Italy\\n\\nAn astronaut onboard the ISS took this photograph of the city lights of Naples and the Campania region of southern Italy on January 30, 2017. The Naples region is one of the brightest in Italy. Roughly three million people live in and around this metropolitan area.\\n\\nThe large black circular area in the photo is Mount Vesuvius, the only active volcano on Europe's mainland. Although any volcanic activity can endanger surrounding communities, eruptive pyroclastic flows of superheated ash and gas are among the most dangerous, moving at speeds of hundreds of kilometers per hour. Vesuvius has erupted on numerous occasions throughout history. Probably the most famous of those eruptions occurred in 79 A.D., when pyroclastic flows destroyed the cities of Pompeii and Herculaneum, trapping more than 16,000 people. Such historic catastrophes\\u2014and the fact that 600,000 people currently live in the immediate vicinity\\u2014are why the volcano is one of the most heavily monitored in the world, with several dozen sensors located at many points on and around the cone.\\n\\nThe different colors of lights in the scene reflect some of the history of development in the area. The green lights are mercury vapor bulbs, an older variety that has been replaced in newer developments by yellow-orange sodium bulbs. To the northeast, the lightless gaps between the homes and businesses are agricultural fields. The bright yellow-orange complex amidst the fields is the Consorzio Intercomunale dei Servizi, the largest commercial facility in Europe. A regional view of Italy appears on page 92.\\n\\n**Date of Photograph:** January 30, 2017\\n\\nKey points on the ground:\\n\\n- Agnano\\n- Naples\\n- Bay of Naples\\n\\n**Orientation:** North (N)\\n\\n---\\n\\n<!-- PageFooter=\\\"Earth at Night\\\" -->\\n<!-- PageNumber=\\\"90\\\" -->\",\n",
      "      \"page_number\": 106\n",
      "    },\n",
      "    \"reranker_score\": 2.1021314,\n",
      "    \"doc_key\": \"earth_at_night_508_page_106_verbalized\"\n",
      "  },\n",
      "  {\n",
      "    \"type\": \"searchIndex\",\n",
      "    \"id\": \"9\",\n",
      "    \"activity_source\": 2,\n",
      "    \"source_data\": {\n",
      "      \"id\": \"earth_at_night_508_page_188_verbalized\",\n",
      "      \"page_chunk\": \"January 2012 and is being processed on a daily basis within 3-5 hours after acquisition, enabling both near-real-time uses and long-term monitoring applications. Detailed information on product generation, applications, and documentation can be found at the product's website: [https://blackmarble.gsfc.nasa.gov](https://blackmarble.gsfc.nasa.gov).\\n\\nThese products are not just visually appealing maps of Earth at night. They provide a global, nighttime, environmental-science-quality dataset that supports all major scientific disciplines focused on the nocturnal environment. These data are particularly valuable for targeted studies of phenomena and processes including:\\n\\n- Light pollution\\n- Urbanization science\\n- Disaster response\\n- Clouds and aerosols\\n- Ocean studies at night\\n- Applications related to energy access, disaster risk reduction, and resilience\\n\\nThe daily records are essential for a broad range of users, such as city planners, ecologists, economists, and emergency responders\\u2014especially when assessing damage from major storms like Hurricane Maria (see pages 118-121 of this volume). Because nighttime light largely results from human activity, these products enhance our understanding of human processes on land and at sea, as well as interactions between human systems and the broader environment.\\n\\n---\\n\\n*Page Footer: 172 Earth at Night*\",\n",
      "      \"page_number\": 188\n",
      "    },\n",
      "    \"reranker_score\": 2.097745,\n",
      "    \"doc_key\": \"earth_at_night_508_page_188_verbalized\"\n",
      "  }\n",
      "]\n"
     ]
    }
   ],
   "source": [
    "retrieval_result = retrieval_results.get(message.id)\n",
    "if retrieval_result is None:\n",
    "    raise RuntimeError(f\"No retrieval results found for message {message.id}\")\n",
    "\n",
    "print(\"Retrieval activity\")\n",
    "print(json.dumps([activity.as_dict() for activity in retrieval_result.activity], indent=2))\n",
    "print(\"Retrieval results\")\n",
    "print(json.dumps([reference.as_dict() for reference in retrieval_result.references], indent=2))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "04661708",
   "metadata": {},
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "0926264d",
   "metadata": {},
   "source": [
    "## Clean up objects and resources\n",
    "\n",
    "If you no longer need the resources, be sure to delete them from your Azure subscription.  You can also delete individual objects to start over.\n",
    "\n",
    "### Delete the agent"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "id": "d67f8609",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Knowledge agent 'earth-search-agent' deleted successfully\n"
     ]
    }
   ],
   "source": [
    "index_client = SearchIndexClient(endpoint=endpoint, credential=credential)\n",
    "index_client.delete_agent(agent_name)\n",
    "print(f\"Knowledge agent '{agent_name}' deleted successfully\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ff523474",
   "metadata": {},
   "source": [
    "### Delete the knowledge source"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "id": "e35a6eb0",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Knowledge source 'earth-at-night-ks' deleted successfully.\n"
     ]
    }
   ],
   "source": [
    "index_client = SearchIndexClient(endpoint=endpoint, credential=credential)\n",
    "index_client.delete_knowledge_source(knowledge_source=knowledge_source_name) # This is new feature in 2025-08-01-Preview api version\n",
    "print(f\"Knowledge source '{knowledge_source_name}' deleted successfully.\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "882ea545",
   "metadata": {},
   "source": [
    "### Delete the index"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d9895f27",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Index 'earth_at_night' deleted successfully\n"
     ]
    }
   ],
   "source": [
    "index_client = SearchIndexClient(endpoint=endpoint, credential=credential)\n",
    "index_client.delete_index(index)\n",
    "print(f\"Index '{index_name}' deleted successfully\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "agentic-retrieval-pipeline-example",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
